
/////////////////////////////////////使用文档////////////////////////////////////////////

/*
log:
last date:
2025-4-22

*/

/*
此APP旨在能让用户轻易在设备上部署基于LVGL的状态栏功能
用户可通过提供的相关指令进行动态创建、删除状态栏内的各种通知、控制、显示组件
提供丰富的功能供使用，用户可按需裁剪
库运行依赖：LVGL、app_manager(启凡科创)、topic_messager(启凡科创)
如不想依赖：
app_manager(启凡科创)、topic_messager(启凡科创)
这两个库，可在conf.h内进行关闭，将提供用户API(user_api.h)进行交互
建议移植上面两个库进行APP之间无耦合开发方式，提升APP移植性和独立性

状态栏在运行过程中，可能会产生以下启动APP事件：
APP:"设置"   参数："WLAN"  "热点"  "蓝牙"  "飞行模式"  "音乐"

如使能了topic_messager库通信，则需要注意以下内容：

状态栏在运行时，会发布主题信息，用于查询电量、时间等数据，主题信息包括（如未启用相关控件则不会执行）：
 "获取时间"          获取信息为7字节：年月日周时分秒，年只携带个位和十位，周为0-6，0为周日
 "获取电量"          获取信息为1字节:0-100
 "获取屏幕亮度"      获取信息为1字节:0-100
 "获取WIFI状态"     获取信息为1字节:0：关闭，  1：开启
 "获取WIFI信号"     获取信息为1字节:0-4为信号强度等级,超过4为无连接
 "获取WIFI名称"     获取信息为字符串
 "获取蓝牙状态"     获取信息为1字节:0：关闭，  1：开启
 "获取蓝牙信号 "    获取信息为1字节:0：关闭，  1：开启
 "获取蓝牙名称"     获取信息为字符串
 "获取热点状态"     获取信息为1字节:0：关闭，  1：开启
 "获取飞行模式状态"  获取信息为1字节:0：关闭，  1：开启
 "获取手电筒状态"   获取信息为1字节:0：关闭，  1：开启
 "获取音量"         获取信息为1字节:0-100
 "获取音乐状态"     获取信息为1字节:0：无来源，  1：暂停中 2：播放中
 "获取音乐时间"     获取信息为4字节：两个uint16_t，第一个为当前播放时间，第二个为总时长


 状态栏已订阅以下主题，在以下主题发布时，将在发布以下主题消息事件时执行相关操作（如未启用相关控件则不会执行）：
 "时间更新"             获取的信息为7字节：年月日周时分秒，年只携带个位和十位，周为0-6，0为周日
 "电量更新"             获取的信息为1字节:0-100
 "WIFI信号更新"         获取的信息为1字节:0-4为信号强度等级，超过4为无连接状态栏不显示
 "蓝牙信号更新"         获取的信息为1字节:0：已断开，1：已连接
 "充电状态更新"         获取的信息为1字节:0：已断开，1：已连接
 "状态栏显示"           获取的信息为1字节:0：隐藏，  1：显示
 "状态栏展开"           获取的信息为1字节:0：折叠，  1：展开信息中心， 2：展开控制中心



控制中心控件用户操作时会发布以下主题事件，设备可以订阅以下事件实现相应控制（如未启用相关控件则不会执行）：
 "设置屏幕亮度"         携带信息为1字节:0-100
 "设置手电筒状态"        携带信息为1字节:0：关闭，  1：开启
 "开始截图"              无携带信息
 "设置WIFI状态"          携带信息为1字节:0：关闭，  1：开启
 "设置蓝牙状态"          携带信息为1字节:0：关闭，  1：开启
 "设置热点状态"          携带信息为1字节:0：关闭，  1：开启
 "设置飞行模式状态"      携带信息为1字节:0：关闭，  1：开启
 "开始锁屏"             无携带信息
 "音乐控制"             携带信息为1字节:0：上一曲，  1：下一曲，  2：暂停，  3：播放


以下为通过topic_messenger创建自定义控件的操作方法：
1. 使用topic_messenger_list_create()创建list;
2. 使用topic_messenger_list_add()添加参数项到list;
3. 使用topic_messenger_smg()发布主题消息，携带list;

注意!!!
用户数据不能是局部变量，需要是不会变动的常量或全局变量，控件会使用此地址数据进行相关事件任务
创建自定义控件一定要在app完成初始化之后才能进行，也就是调用了app_status_bar_register()之后才能进行

在控制中心创建圆形开关按钮：
主题： "状态栏创建开关"
数据list内容（可选的部分可不添加到list），注意lenth参数一定要对应，app内靠此参数进行数据类型判断：

//可选, 如不添加此参数，则不显示图标
1. userdata: 按钮上显示的图标，图标转换格式为CF_TRUE_COLOR_ALPHA，图标大小请自行测试
   lenth:1

//必选
2. userdata: 创建的行列位置，2字节数组，第一字节为列X，第二字节为行Y，如(0,0)为第一行第一列，(3,2)为第二行第三列，以此类推，屏左上角为0,0，向右为X轴，向下为Y轴
   lenth:2

//可选, 如不添加此参数，则不产生点击事件
3. userdata: 点击后发布的主题名称字符串,如"设置WIFI状态"
   lenth:3

//可选, 如不添加此参数，则按钮只存在未打开的状态，仅在点击时会产生对应主题通知且不携带状态数据（如未添加3，则此参数弃用）
4. userdata: 查询对应状态的字符串，如"获取WIFI状态"，状态栏展开后，按钮会持续获取对应状态更新显示，
            用户需要topic_messenger_subscribe()订阅此主题，返回对应状态,类型为uint8_t,0为关闭，1为开启
   lenth:4

//可选, 如不添加此参数，则不开启长按事件，此功能依赖于app_manager库
5. userdata: 长按后要打开的APP的名称字符串,如长按此按钮打开的APP名称可设置为"智能家居"，携带的数据为第6项"WLAN"
   lenth:5

//可选，如不添加此参数，则长按事件（如果启用长按事件）时携带数据为NULL
6. userdata: 携带给APP的数据，如字符串"WLAN"或其他类型数据，需要与对应APP进行协商
   lenth:6

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

在控制中心创建滑动条：
主题： "状态栏创建滑动条"
数据list内容（可选的部分可不添加到list），注意lenth参数一定要对应，app内靠此参数进行数据类型判断：

//可选, 如不添加此参数，则不显示图标
1. userdata: 按钮上显示的图标，图标转换格式为CF_TRUE_COLOR_ALPHA，图标大小请自行测试
   lenth:1

//必选
2. userdata: 创建的行列位置，2字节数组，第一字节为列X，第二字节为行Y，如(0,0)为第一行第一列，(3,2)为第二行第三列，以此类推，屏左上角为0,0，向右为X轴，向下为Y轴
   lenth:2

//可选, 如不添加此参数，则不产生用户更改数值事件，事件携带的数据类型为int16_t
3. userdata: 点击后发布的主题名称字符串,如"设置音量"
   lenth:3

//可选, 如不添加此参数，则滑动条无法同步被其他程序修改后的被控数据
4. userdata: 查询对应状态的字符串，如"获取音量"，状态栏展开后，按钮会持续获取对应状态更新显示，
            用户需要topic_messenger_subscribe()订阅此主题，返回对应数据值,类型为int16_t
   lenth:4

//必选，滑动条上下范围值
5. userdata: 两个int16_t成员的数组，第一个为最小值，第二个为最大值
   lenth:7

   //////////////////////////////////////////////////////////////////////////////////////////////////////////

创建打开/关闭WIFI的按钮示例：

LV_IMG_DECLARE(status_bar_wlan_switch_icon);             //图标声明
uint8_t now_wifi_sta;                                    // wifi状态 0：关闭，  1：开启

static void get_wifi_sta_cb(void *userdata, size_t size) // 状态栏展开时会调用此函数查询状态
{
    *(uint8_t *)userdata = now_wifi_sta;                 // 返回WIFI开关状态
}

static void set_wifi_sta_cb(void *userdata, size_t size) // 用户按下按钮时会调用此函数设置状态
{
    now_wifi_sta = *(uint8_t *)userdata;                 // 获取控制状态
    if (now_wifi_sta)
    {
        // 打开wifi
    }
    else
    {
        // 关闭wifi
    }
}

static void create_wifi_switch()//调用此函数即可
{
    uint8_t pos[2] = {0,5}; // 第6行第1列

    topic_messenger_list_t list = topic_messenger_list_create();                //创建表

    topic_messenger_list_add(list, (void *)&status_bar_wlan_switch_icon, 1);   //可选，不添加此行则不显示图标
    topic_messenger_list_add(list, pos, 2);                                     //必选，设置位置
    topic_messenger_list_add(list, (void *)"设置WIFI状态", 3);                  //可选，不添加此行则不产生点击事件，如只需要长按或只需要显示状态的功能
    topic_messenger_list_add(list, (void *)"获取WIFI状态", 4);                  //可选，不添加此行则此按钮点击事件只有0（比如截屏这一类功能，点击后不需要开关状态）
    topic_messenger_list_add(list, (void *)"设置", 5);                          //可选，不添加此行则不开启长按事件（没有对应的管理APP则不需要此功能）
    topic_messenger_list_add(list, (void *)"WLAN", 6);                          //可选，不添加此行则在长按（如启用了）时打开对应APP，携带的数据为NULL

    topic_messenger_msg("状态栏创建开关", &list, 0);                              // 发布主题消息进行创建

    topic_messenger_subscribe(NULL, "获取WIFI状态", get_wifi_sta_cb);                  // 订阅主题消息获取状态
    topic_messenger_subscribe(NULL, "设置WIFI状态", set_wifi_sta_cb);                  // 订阅主题消息设置状态
}

此示例功能：
在控制中心第6行第1列创建了一个控制WLAN开关的按钮
状态栏展开时，按钮会持续发布主题"获取WIFI状态"获取对应状态更新显示
按钮被点击时，会发布主题"设置WIFI状态"通知，携带状态0或1，用户订阅此主题即可获取状态0和1进行相应控制
当按钮被长按时，会打开APP名称为"设置"的APP，携带的数据为第一项"WLAN"，设置APP此时即可打开后跳转到WLAN页面（自行实现设置APP）

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

创建打开"电子书"APP示例：
static void create_book_switch()
{
    uint8_t pos[2] = {1,5}; // 第6行第2列

    topic_messenger_list_t list = topic_messenger_list_create();   //创建表

    topic_messenger_list_add(list, pos, 2);                        //必选，设置位置
    topic_messenger_list_add(list, (void *)"电子书", 5);           //可选，不添加此行则不开启长按事件（没有对应的管理APP则不需要此功能）
    topic_messenger_list_add(list, (void *)"毛泽东选集", 6);       //可选，不添加此行则在长按（如启用了）时打开对应APP，携带的数据为NULL

    topic_messenger_msg("状态栏创建开关", &list, 0);                // 发布主题消息进行创建
}

此示例功能：
在控制中心第6行第2列创建了一个打开"电子书"APP的无图标按钮
当按钮被长按时，会打开APP名称为"电子书"的APP，携带的数据为"毛泽东选集"

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

创建自定义滑动条示例：

LV_IMG_DECLARE(status_bar_slider_volce_icon);//图标声明
int16_t vol = 50; // 音量大小

static void get_volce_cb(void *userdata, size_t size) // 状态栏展开时会调用此函数查询参数
{
    *(int16_t *)userdata = vol; // 返回音量大小
}

static void set_volce_cb(void *userdata, size_t size) // 用户滑动滑动条时会调用此函数设置参数
{
    vol = *(uint16_t *)userdata; // 获取音量大小
    // 设置音量
    printf("volce:%d\n", vol);
}

static void create_volce_slider()//调用此函数即可
{
    uint8_t pos[2] = {2,5};                                                     // 第6行第3列
    int16_t range[2] = {0,100};                                                 // 音量范围

    topic_messenger_list_t list = topic_messenger_list_create();                //创建表

    topic_messenger_list_add(list, (void *)&status_bar_wlan_switch_icon, 1);   //可选，不添加此行则不显示图标
    topic_messenger_list_add(list, pos, 2);                                     //必选，设置位置
    topic_messenger_list_add(list, (void *)"设置音量", 3);                      //可选，不添加此行则不产生更改事件，如只需要长按或只需要显示某个数据的功能
    topic_messenger_list_add(list, (void *)"获取音量", 4);                      //可选，不添加此行则滑动条不会同步系统数据，显示不实时
    topic_messenger_list_add(list, (void *)range, 7);                          //必选，滑动条数据范围


    topic_messenger_msg("状态栏创建滑动条", &list, 0);                            // 发布主题消息进行创建

    topic_messenger_subscribe(NULL, "获取音量", get_volce_cb);                  // 订阅主题消息获取数据
    topic_messenger_subscribe(NULL, "设置音量", set_volce_cb);                  // 订阅主题消息设置数据
}

此示例功能：
在控制中心第6行第3列创建了一个控制音量大小的滑动条
状态栏展开时，按钮会持续发布主题"获取音量"获取对应数据大小
按滑动条被滑动时，会发布主题"设置音量"通知，携带音量数据，用户订阅此主题即可获取音量大小进行相应控制

   //////////////////////////////////////////////////////////////////////////////////////////////////////////





*/
